Next: , Previous: Type Conversion, Up: Top

4 Calling methods in a blocking way.

Methods can be called synchronously (blocking) or asynchronously (non-blocking).

At D-Bus level, a method call consist of two messages: one message which carries the input parameters to the object owning the method to be called, and a reply message returning the resulting output parameters from the object.

— Function: dbus-call-method bus service path interface method &optional :timeout timeout &rest args

This function calls method on the D-Bus bus. bus is either the symbol :system or the symbol :session.

service is the D-Bus service name to be used. path is the D-Bus object path, service is registered at. interface is an interface offered by service. It must provide method.

If the parameter :timeout is given, the following integer timeout specifies the maximum number of milliseconds the method call must return. The default value is 25,000. If the method call doesn't return in time, a D-Bus error is raised (see Errors and Events).

All other arguments args are passed to method as arguments. They are converted into D-Bus types as described in Type Conversion.

The function returns the resulting values of method as a list of Lisp objects, according to the type conversion rules described in Type Conversion. Example:

          (dbus-call-method
            :session "org.gnome.seahorse" "/org/gnome/seahorse/keys/openpgp"
            "org.gnome.seahorse.Keys" "GetKeyField"
            "openpgp:657984B8C7A966DD" "simple-name")

          ⇒ (t ("Philip R. Zimmermann"))

If the result of the method call is just one value, the converted Lisp object is returned instead of a list containing this single Lisp object. Example:

          (dbus-call-method
            :system "org.freedesktop.Hal"
            "/org/freedesktop/Hal/devices/computer"
            "org.freedesktop.Hal.Device" "GetPropertyString"
            "system.kernel.machine")

          ⇒ "i686"

With the dbus-introspect function it is possible to explore the interfaces of ‘org.freedesktop.Hal’ service. It offers the interfaces ‘org.freedesktop.Hal.Manager’ for the object at the path ‘/org/freedesktop/Hal/Manager’ as well as the interface ‘org.freedesktop.Hal.Device’ for all objects prefixed with the path ‘/org/freedesktop/Hal/devices’. With the methods ‘GetAllDevices’ and ‘GetAllProperties’, it is simple to emulate the lshal command on GNU/Linux systems:

          (dolist (device
                    (dbus-call-method
                      :system "org.freedesktop.Hal"
                      "/org/freedesktop/Hal/Manager"
                      "org.freedesktop.Hal.Manager" "GetAllDevices"))
            (message "\nudi = %s" device)
            (dolist (properties
                      (dbus-call-method
                        :system "org.freedesktop.Hal" device
                        "org.freedesktop.Hal.Device" "GetAllProperties"))
              (message "  %s = %S"
                       (car properties) (or (caar (cdr properties)) ""))))

          -| "udi = /org/freedesktop/Hal/devices/computer
                info.addons = (\"hald-addon-acpi\")
                info.bus = \"unknown\"
                info.product = \"Computer\"
                info.subsystem = \"unknown\"
                info.udi = \"/org/freedesktop/Hal/devices/computer\"
                linux.sysfs_path_device = \"(none)\"
                power_management.acpi.linux.version = \"20051216\"
                power_management.can_suspend_to_disk = t
                power_management.can_suspend_to_ram = \"\"
                power_management.type = \"acpi\"
                smbios.bios.release_date = \"11/07/2001\"
                system.chassis.manufacturer = \"COMPAL\"
                system.chassis.type = \"Notebook\"
                system.firmware.release_date = \"03/19/2005\"
                ..."
— Function: dbus-call-method-non-blocking bus service path interface method &optional :timeout timeout &rest args

Call method on the D-Bus bus, but don't block the event queue. This is necessary for communicating to registered D-Bus methods, which are running in the same Emacs process.

The arguments are the same as in dbus-call-method. Example:

          (dbus-call-method-non-blocking
            :system "org.freedesktop.Hal"
            "/org/freedesktop/Hal/devices/computer"
            "org.freedesktop.Hal.Device" "GetPropertyString"
            "system.kernel.machine")

          ⇒ "i686"